/*
 * Copyright (C) 2012  Romain DUBOIS
 * 
 * This file is part of NeMoS - Network and Modular Software
 * 
 * NeMoS is free software: you can redistribute it and/or modify
 * it under the terms of the GNU General Public License as published by
 * the Free Software Foundation, either version 3 of the License, or
 * (at your option) any later version.
 * 
 * NeMoS is distributed in the hope that it will be useful,
 * but WITHOUT ANY WARRANTY; without even the implied warranty of
 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
 * GNU General Public License for more details.
 * 
 * You should have received a copy of the GNU General Public License
 * along with NeMoS.  If not, see <http://www.gnu.org/licenses/>.
 */
package nemos.resources;

import java.util.Locale;
import java.util.ResourceBundle;
import java.util.Set;

/**
 * IResources : The localized resources node interface.
 * 
 * <p>
 * This interface is a typed-adaptation of the {@link ResourceBundle} class.
 * </p>
 * 
 * @author Romain DUBOIS
 * @param <T>
 *            The node resources type
 */
public interface IResources<T> {

    /**
     * Test if a resource matches the specified key. This method guarantees to
     * return as fast as a call to <code>keySet.contains()</code>, or even
     * faster.
     * 
     * @param pKey
     *            The key to test
     * @return If a resource associated to the key exists
     */
    boolean containsKey(String pKey);

    /**
     * Get the node locale.
     * 
     * @return The node locale
     */
    Locale getLocale();

    /**
     * Get the keys of all the existing resources.
     * 
     * @return The resources keys
     */
    Set<String> keySet();

    /**
     * Get the resource associated to the specified key. It returns a
     * <code>null</code> object rather than throwing an exception if the
     * resource does not exist.
     * 
     * @param pKey
     *            The required resource key
     * @return The resource or <code>null</code> if it does not exist
     */
    T getResource(String pKey);

    /**
     * This method can be used to check type validity at runtime while
     * collecting the node rather than facing a {@link ClassCastException} while
     * calling the {@link #getResource(String)} method.
     * 
     * @param pNewType
     *            The type to adapt to
     * @return An adapted {@link IResources} of the current one.
     * @throws ClassCastException
     *             If the current resources can not adapt to the required type
     */
    <U> IResources<U> adapt(Class<U> pNewType);
}
